From f109780159e93f9ef29c0d4cad7a75ad2e3a5def Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Thu, 17 Feb 2005 03:33:11 +0000 Subject: [PATCH] Add some information about the icon cache format (since I can't locate it 2005-02-16 Matthias Clasen * docs/iconcache.txt: Add some information about the icon cache format (since I can't locate it at freedesktop.org) --- ChangeLog | 3 ++ ChangeLog.pre-2-10 | 3 ++ ChangeLog.pre-2-8 | 3 ++ docs/iconcache.txt | 125 +++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 134 insertions(+) create mode 100644 docs/iconcache.txt diff --git a/ChangeLog b/ChangeLog index 6d6831f608..a090de8750 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,5 +1,8 @@ 2005-02-16 Matthias Clasen + * docs/iconcache.txt: Add some information about the + icon cache format (since I can't locate it at freedesktop.org) + Fixes for #143829, Tommi Komulainen, Christian Persch: * gtk/gtktreeview.c (gtk_tree_view_destroy): Remove the diff --git a/ChangeLog.pre-2-10 b/ChangeLog.pre-2-10 index 6d6831f608..a090de8750 100644 --- a/ChangeLog.pre-2-10 +++ b/ChangeLog.pre-2-10 @@ -1,5 +1,8 @@ 2005-02-16 Matthias Clasen + * docs/iconcache.txt: Add some information about the + icon cache format (since I can't locate it at freedesktop.org) + Fixes for #143829, Tommi Komulainen, Christian Persch: * gtk/gtktreeview.c (gtk_tree_view_destroy): Remove the diff --git a/ChangeLog.pre-2-8 b/ChangeLog.pre-2-8 index 6d6831f608..a090de8750 100644 --- a/ChangeLog.pre-2-8 +++ b/ChangeLog.pre-2-8 @@ -1,5 +1,8 @@ 2005-02-16 Matthias Clasen + * docs/iconcache.txt: Add some information about the + icon cache format (since I can't locate it at freedesktop.org) + Fixes for #143829, Tommi Komulainen, Christian Persch: * gtk/gtktreeview.c (gtk_tree_view_destroy): Remove the diff --git a/docs/iconcache.txt b/docs/iconcache.txt new file mode 100644 index 0000000000..2cae3e0a43 --- /dev/null +++ b/docs/iconcache.txt @@ -0,0 +1,125 @@ +Information about the icon theme cache format used by GTK+ +for more information, see the mailing list threads at + +http://mail.gnome.org/archives/gtk-devel-list/2004-April/msg00065.html +http://lists.freedesktop.org/archives/xdg/2004-October/005140.html + + +Back in May, Owen Taylor proposed [1] caching scheme for icon theme +information, to reduce the amount of stating and disk seeking at +application startup, and to reduce the memory overhead if each app +allocates all the icon theme data separately. + +The proposal is to keep the information about the icons in the +directory tree below each icon theme directory in an mmap()able +cache file (There is basically one cache file per index.theme file). + +The cache doesn't try to hold all information from the index.theme files +that you would need to do lookups; it turns out that with the icon theme +specification, this isn't even sensible - you can install a + + $HOME/.local/share/icons/Bluecurve/index.theme + +That overrides + + /usr/share/icons/Bluecurve/index.theme + +and chances how lookup happens for icons in /usr/share/icons/Bluecurve. + +We would like to propose the cache file format as an appendix to the +icon theme specification. One thing which still needs to be investigated +is caching of the actual image data; the file format is has an +IMAGE_DATA_OFFSET member to allow adding that compatibly. An +implementation of the caching scheme for GTK+ can be found at [2]. The +cache generator which is included in the patch depends only on glib, and +it may be a good idea to move it to freedesktop.org as well. + + +Regards, Matthias Clasen + + +The cache file format: + +Header: +2 CARD16 MAJOR_VERSION 1 +2 CARD16 MINOR_VERSION 0 +4 CARD32 HASH_OFFSET +4 CARD32 DIRECTORY_LIST_OFFSET + +DirectoryList: +4 CARD32 N_DIRECTORIES +4*N_DIRECTORIES CARD32 DIRECTORY_OFFSET + +Hash: +4 CARD32 N_BUCKETS +4*N_BUCKETS CARD32 ICON_OFFSET + +Icon: +4 CARD32 CHAIN_OFFSET +4 CARD32 NAME_OFFSET +4 CARD32 IMAGE_LIST_OFFSET + +ImageList: +4 CARD32 N_IMAGES +8*N_IMAGES Image IMAGES + +Image: +2 CARD16 DIRECTORY_INDEX +2 ICON_FLAGS FLAGS +4 CARD32 IMAGE_DATA_OFFSET + +ICON_FLAGS +HAS_SUFFIX_PNG 1 +HAS_SUFFIX_XPM 2 +HAS_SUFFIX_SVG 4 +HAS_ICON_FILE 8 + + +Notes: + +* All offsets are from in bytes from the beginning of the file + +* Strings are zero-terminated + +* Directories are stored as relative paths. + +* All numbers are in network (big-endian) order. This is + necessary because the data will be stored in arch-independent + directories like /usr/share/icons or even in user's + home directories. + +* The hash function is that used by g_str_hash() + + unsigned int + icon_str_hash (gconstpointer key) + { + const char *p = key; + unsigned int h = *p; + + if (h) + for (p += 1; *p != '\0'; p++) + h = (h << 5) - h + *p; + + return h; + } + + This should not be implemented by calling g_str_hash(). For + optimal results, N_BUCKETS should be typically be prime. + +* The same file format is used for icon themes (e.g., + /usr/share/icons/Bluecurve) and for unthemed icon directories + (e.g., /usr/share/pixmaps) + + For an unthemed directory, N_DIRECTORIES==0 and each + image has a DIRECTORY_INDEX field of 0xFFFF. + +* Up-to-dateness of a cache file is determined simply: + + If the mod-time on the directory where the cache file + lives is newer than the mod-time of the cache file, + the cache file is out of date. + +* Cache files have to be written atomically - write to a + temporary name, then move over the old file - so that + clients that have the old cache file open and mmap'ed + won't get corrupt data. -- 2.30.2